package com.smart.community.property.service;

import com.smart.community.property.dto.PropertyInfoDTO;
import com.smart.community.property.vo.PropertyInfoStatsVO;
import com.smart.community.commons.vo.property.PropertyInfoVO;

/**
 * 物业信息管理服务接口
 * 提供物业公司信息的查询、更新、统计等功能
 * 
 * 严格按照《Java后端SpringBoot代码开发规范.md》Service层规范实现：
 * - 生产环境标准：移除throws Exception声明，使用统一异常处理
 * - 职责分离：Service接口专注于业务逻辑定义
 * - 异常处理：完善的异常处理和日志记录
 * - 缓存策略：合理的缓存键设计和失效策略
 * - 性能监控：详细的性能指标记录
 * 
 * @author Wu.Liang
 * @since 2025-01-30
 * @version 2.0.0 - 生产环境标准优化，移除throws Exception声明
 */
public interface IPropertyInfoService {

    /**
     * 根据物业公司ID获取物业信息
     * 
     * @param propertyCompanyId 物业公司ID
     * @return 物业信息VO，获取失败时返回null
     */
    PropertyInfoVO getPropertyInfo(Long propertyCompanyId);

    /**
     * 获取物业公司信息统计
     * 
     * @param propertyCompanyId 物业公司ID
     * @return 统计信息，获取失败时返回默认值
     */
    PropertyInfoStatsVO getPropertyInfoStats(Long propertyCompanyId);

    /**
     * 更新物业公司信息
     * 
     * @param propertyInfoDTO 物业信息更新DTO
     * @return 是否更新成功
     */
    boolean updatePropertyInfo(PropertyInfoDTO propertyInfoDTO);

    /**
     * 获取当前用户关联的物业公司信息
     * 
     * @param userId 用户ID
     * @return 物业信息VO，获取失败时返回null
     */
    PropertyInfoVO getCurrentUserPropertyInfo(Long userId);

    /**
     * 获取当前用户关联的物业公司统计信息
     * 
     * @param userId 用户ID
     * @return 统计信息，获取失败时返回默认值
     */
    PropertyInfoStatsVO getCurrentUserPropertyInfoStats(Long userId);

    /**
     * 检查用户是否有关联的物业公司
     * 
     * @param userId 用户ID
     * @return 是否有关联的物业公司
     */
    boolean hasPropertyCompany(Long userId);
} 